
<!DOCTYPE html>
<html>
  <head>
    <title>module folktale/adt/union</title>
    <link rel="stylesheet" href="prism.css">
    <link rel="stylesheet" href="style.css">
  </head>
  <body>
    <div id="header">
      <div class="doc-title"><a href="folktale.html"><span class="doc-title"><span class="product-name">Folktale</span><span class="version">v2.3.0</span></span></a><ul class="navigation"><li class="navigation-item"><a href="https://github.com/origamitower/folktale" title="">GitHub</a></li><li class="navigation-item"><a href="/docs/support/" title="">Support</a></li><li class="navigation-item"><a href="/docs/v2.3.0/contributing/" title="">Contributing</a></li></ul></div>
    </div>
    <div id="content-wrapper"><div id="content-panel"><h1 class="entity-title">module folktale/adt/union</h1><div class="highlight-summary"><div><p>Provides utilities to define tagged unions.</p>
</div></div><div class="deprecation-section"><strong class="deprecation-title">This feature is experimental!</strong><p>This API is still experimental, so it may change or be removed in future versions. You should not rely on it for production applications.</p></div><h2 class="section-title">Documentation</h2><div class="documentation"><div><p>Provides utilities to define tagged unions.</p>
<h2 id="programming-with-tagged-unions">Programming with Tagged Unions</h2>
<p>Modelling data is important for a range of reasons. From performance
to correctness to safety. Tagged unions give you a way of modelling
choices that forces the correct handling of them, unlike predicate-based
branching, such as the one used by if statements and other common 
control flow structures.</p>
<p>Most of the structures provided by Folktale are tagged unions. But
Folktale also gives you a primitive for constructing new ones in an
easy way. The <code>union</code> function provided by this module achieves that
goal:</p>
<pre><code>const union = require(&#39;folktale/adt/union/union&#39;);

const Maybe = union(&#39;Maybe&#39;, {
  Some(value){ return { value } },
  None() { return {} }
});

Maybe.Some(1).matchWith({
  Some: ({ value }) =&gt; `Found ${value}`,
  None: ()          =&gt; &quot;Not found&quot; 
});
// ==&gt; &quot;Found 1&quot;
</code></pre><p>Tagged unions constructed by this module allow one to easily bestow
common functionality in them through the <code>derive</code> function. For example,
one could add the concept of equality to the <code>Maybe</code> data structure
constructed previously by using the <code>Equality</code> derivation, which is also
provided by this module:</p>
<pre><code>const Equality = require(&#39;folktale/adt/union/derivations/equality&#39;);
Maybe.derive(Equality);

Maybe.Some(1).equals(Maybe.Some(1)); // ==&gt; true
Maybe.Some(2).equals(Maybe.Some(1)); // ==&gt; false
</code></pre><p>These structures also provide a way of testing if a value belongs to
an Union in a cross-realm way using the <code>.hasInstance</code> method on the Union
or variant:</p>
<pre><code>Maybe.hasInstance(Maybe.None());       // ==&gt; true
Maybe.Some.hasInstance(Maybe.None());  // ==&gt; false
Maybe.Some.hasInstance(Maybe.Some(1)); // ==&gt; true
</code></pre><p>See the documentation on the <code>data</code> function for details.</p>
<h2 id="what-s-in-adt-union-">What&#39;s in <code>adt/union</code>?</h2>
<p><code>adt/union</code> provides features to construct tagged unions, and common
derivations for those structures. These operations are divided as
follows:</p>
<ul>
<li><p><strong>Constructing Data Structures</strong>: functions that construct new
tagged unions.</p>
</li>
<li><p><strong>Extending Unions</strong>: functions that allow one to extend existing
Unions and variants with new functionality.</p>
</li>
<li><p><strong>Derivation</strong>: functions that can be used as derivations to
provide common functionality to Unions.</p>
</li>
</ul>
</div></div><div class="members"><h2 class="section-title" id="properties">Properties</h2><div class="member-category"><h3 class="category" id="cat-derivations">Derivations</h3><div class="member-list"><div class="member"><a class="member-name" href="folktale.adt.union.derivations.html">derivations</a><div class="doc-summary"><div><p>Pre-built derivations for Folktale unions.</p>
</div></div><div class="special-tags"><span class="tagged experimental">Experimental</span></div></div></div></div><div class="member-category"><h3 class="category" id="cat-modelling-data">Modelling data</h3><div class="member-list"><div class="member"><a class="member-name" href="folktale.adt.union.union.union.html">union(typeId, patterns)</a><div class="doc-summary"><div><p>Constructs a tagged union data structure.</p>
</div></div><div class="special-tags"><span class="tagged experimental">Experimental</span></div></div></div></div></div><div class="source-code"><h2 class="section-title" id="source-code">Source Code</h2><div class="source-location">Defined in source/adt/union/index.js at line 14, column 0</div><pre class="source-code"><code class="language-javascript">{
  union: require('./union'),
  derivations: require('./derivations')
}</code></pre></div></div><div id="meta-panel"><div class="meta-section"><div class="meta-field"><strong class="meta-field-title">Stability</strong><div class="meta-field-value">experimental</div></div><div class="meta-field"><strong class="meta-field-title">Licence</strong><div class="meta-field-value">MIT</div></div><div class="meta-field"><strong class="meta-field-title">Module</strong><div class="meta-field-value">folktale/adt/union</div></div></div><div class="table-of-contents"><div class="meta-section-title">On This Page</div><ul class="toc-list level-1"><li class="toc-item"><span class="no-anchor">Documentation</span><ul class="toc-list level-2"><li class="toc-item"><a href="#programming-with-tagged-unions" title="Programming with Tagged Unions"><div><p>Programming with Tagged Unions</p>
</div></a></li><li class="toc-item"><a href="#what-s-in-adt-union-" title="What's in `adt/union`?"><div><p>What&#39;s in <code>adt/union</code>?</p>
</div></a></li></ul></li><li class="toc-item"><a href="#properties">Properties</a><ul class="toc-list level-2"><li class="toc-item"><a href="#cat-derivations">Derivations</a></li><li class="toc-item"><a href="#cat-modelling-data">Modelling data</a></li></ul></li><li class="toc-item"><a href="#source-code">Source Code</a></li></ul></div><div class="meta-section"><strong class="meta-section-title">Authors</strong><div class="meta-field"><strong class="meta-field-title">Copyright</strong><div class="meta-field-value">(c) 2013-2017 Quildreen Motta, and CONTRIBUTORS</div></div><div class="meta-field"><strong class="meta-field-title">Authors</strong><div class="meta-field-value"><ul class="meta-list"><li>Quildreen Motta</li></ul></div></div><div class="meta-field"><strong class="meta-field-title">Maintainers</strong><div class="meta-field-value"><ul class="meta-list"><li>Quildreen Motta &lt;queen@robotlolita.me&gt; (http://robotlolita.me/)</li></ul></div></div></div></div></div>
    <script>
void function() {
  var xs = document.querySelectorAll('.documentation pre code');
  for (var i = 0; i < xs.length; ++i) {
    xs[i].className = 'language-javascript code-block';
  }
}()
    </script>
    <script src="prism.js"></script>
  </body>
</html>